Directories and User Mapping
Cyberhaven automatically synchronizes local user groups from on-premises Active Directory and Apple Open Directory whereas, Cyberhaven leverages WorkOS to integrate with cloud directory providers.
The Cyberhaven SaaS service integrates with Cloud Directory providers such as Microsoft Entra ID, Okta, Google, JumpCloud, SCIM, etc. using WorkOS. The integration enables Cyberhaven to map users to user accounts in your directory service to correlate local user activities. Cyberhaven uses the email address in the directory service to map each user since email addresses serve as unique identifiers. By using email-based mapping, Cyberhaven ensures accurate and reliable associations between endpoint users and the user directory.
This mapping is done in the Cyberhaven SaaS service, not by Cyberhaven Endpoint Sensors. When the mapping is complete, sensor-generated events on the Risks Overview page will contain the username as defined in your directory service. You can click on the username to view details such as the user groups related to this user in your directory.
NOTE
This feature only works with directory services that have configured email addresses.
Directory Information Without Integration
On both Windows and macOS, the Endpoint Sensors are able to automatically synchronize the local user groups. This happens out of the box and does not require any directory integration to be set up. For instance, on Windows, the group information from on-prem Active Directory or Microsoft Entra ID is synchronized by the operating system and available in the user token. This group information is automatically synchronized by Windows when the user logs in (but cannot be synchronized on demand). The Cyberhaven Windows Endpoint Sensor is able to query the user token and extract the group information automatically. Other directory information is not available without configuring the directory integration in the Cyberhaven Console.
Similarly, on macOS, the Sensor will automatically map the endpoint users to their email address setup within Apple Open Directory. However, if you use Jamf in your environment, then we also provide a new MDM profile to set up email based user mapping. Read more: Enhancing User Mapping on macOS with Jamf.
Integrate multiple directories
Cyberhaven can integrate with multiple user directories and correlate information about a user from the different directories. This information is presented in the context of events generated by the user's activities to provide you with a comprehensive understanding of the user's actions. To identify a user across multiple directories, Cyberhaven requires a consistent email address associated with the user in all the directories. Follow the instructions in Integrating Cyberhaven with Cloud-based User Directories to add multiple directories in your Cyberhaven Console.
Integrating Cyberhaven with Cloud-based User Directories
Users are automatically mapped to the email address configured in the user directory. You must integrate Cyberhaven with your cloud directory services to enable email-based user mapping.
To integrate Cyberhaven with your cloud directory services,
In the Cyberhaven tenant, navigate to Preferences > Directories and user mapping and click Add New. The WorkOS setup page opens in a new browser tab.
On the WorkOS setup page, select the directory provider and follow the setup instructions on the screen. For detailed instructions, follow the WorkOS documentation here, WorkOS Documentation.
When the setup is complete, the directory service is displayed on the Directory Integrations tab. You can click on a linked service in the State column to view the list of users and their usernames.
After integrating with a directory service, the Cyberhaven console synchronizes with WorkOS to update usernames on the Risks Overview page. When updated, the events will show usernames and user groups as per your directory.
The initial synchronization process can take up to 12 hours to complete. After that, the page is updated with directory information every 30 minutes to an hour. Currently, the time to synchronize can only be set up through the backend.
Contact support@cyberhaven.com to change the synchronization interval.
Mapping Okta users with Cyberhaven through custom attributes
If you have setup directory integration with Okta then you can leverage Cyberhaven's capability to establish mappings between endpoint users in Okta and Cyberhaven through custom attributes. This feature works for Okta integrated with a SCIM app. To configure custom atrribute mapping between Okta and Cyberhaven, follow the instructions.
Log into your Okta Admin Console and navigate to Directory > Profile Editor.
Select a SCIM app profile. The list of user attributes from the selected app is displayed.
Add a new custom attribute that you want to map to Cyberhaven. Click Add attribute.
Enter the following details.
Select the data type and enter a name for the attribute.
Enter a name and variable name to refer to this attribute.
Enter the external name for the attribute to be referenced during SAML communications with Cyberhaven.
Enter the external namespace as urn:ietf:params:scim:schemas:core:2.0:User. This is the SAML identifier for this attribute required to securely communicate with Cyberhaven.
Enter a description for the attribute.
Optionally, select the Enum checkbox to specify a set of values related to the attribute.
Define the attribute length.
Select the Attribute required checkbox to indicate that the attribute is required when using the SCIM app.
Set the scope of the attribute and mutability to read-only or hidden as recommended by Okta. Read more: Okta documentation
Click Save. The new custom attribute is added to the Attributes table.
Click on Mappings and then click on Okta User to SCIM tab.
Copy the name of the custom attribute from the SCIM app column.
Log into the Cyberhaven Console and navigate to Preferences > Directories and user mapping
From the list of integrations table click on the linked Okta integration. The WorkOS integration setup page is displayed with the current settings for the Okta integration.
On the integration settings page, click on Edit Attribute Map and in the dialog box paste the custom attribute in the field you want to map to Cyberhaven.
Click Save Mappings.
After the next synchronization between Cyberhaven and WorkOS the new attribute values for the endpoint users will be available in the Cyberhaven Console.
Viewing the status of user mappings
You can view the directory mapping status of all your endpoint users in the User Mapping tab. The "Mapped" status indicates that a user is linked to Cyberhaven through your corporate directory service using directory integration, while the "Unmapped" status means the user is not linked through directory integration. The table presents details including the email address of the mapped user, matching with their email in your directory service. It also shows the hostname, local username, the type and version of the Cyberhaven Sensor, and the name of the directory service used for mapping.
For unmapped users, the Details column displays a message explaining the reason behind the lack of mapping. The Troubleshooting section includes information about the messages in the Details column.
Troubleshooting
After linking the directory service to Cyberhaven if you are not seeing user data in your Cyberhaven UI, then verify that the Cyberhaven processes are not being blocked by a policy.
If the status details display the message "Email address reported by endpoint not found in user directory" then, ensure that the email address field in your user directory is mapped correctly to Cyberhaven.
For mapping with Okta, see the section, Mapping Okta users with Cyberhaven through custom attributes.
For mapping with Jamf, see the section, Enhancing User Mapping on macOS with Jamf.
If the status details display the message "Email address not reported by endpoint" then, ensure that user directory integration is set up correctly. See the instructions at the beginning of this article.